问题

Problem

编辑器中的红色波浪线是不够的：您需要命令行反馈、状态代码、配置和选项来对 JavaScript 进行类型检查并编译 TypeScript。

Red squigglies in the editor are not enough: you want command-line feedback, status codes, configuration, and options to type-check JavaScript and compile TypeScript.

解决方案

Solution

通过 Node 的主包注册表安装 TypeScript：NPM。

Install TypeScript via Node’s primary package registry: NPM.

讨论

Discussion

TypeScript 用 TypeScript 编写，编译为 JavaScript，并使用Node.js JavaScript 运行时作为其主要执行环境。2^即使您没有编写 Node.js 应用程序，JavaScript 应用程序的工具也将在 Node 上运行。因此，请确保从官方网站获取 Node.js并熟悉其命令行工具。

TypeScript is written in TypeScript, compiled to JavaScript, and uses the Node.js JavaScript runtime as its primary execution environment.² Even if you’re not writing a Node.js app, the tooling for your JavaScript applications will run on Node. So, make sure you get Node.js from the official website and get familiar with its command-line tools.

对于新项目，请确保使用新的package.json初始化项目文件夹 。此文件包含 Node 及其包管理器 NPM 的所有信息，以确定项目的内容。使用 NPM 命令行工具在项目文件夹中生成一个具有默认内容的新package.json文件：

For a new project, make sure you initialize your project’s folder with a fresh package.json. This file contains all the information for Node and its package manager NPM to figure out your project’s contents. Generate a new package.json file with default contents in your project’s folder with the NPM command-line tool:

$  npm  init  -y

$ npm init -y

NPM 是 Node 的包管理器。它带有 CLI、注册表和其他允许您安装依赖项的工具。初始化package.json后，从 NPM 安装 TypeScript 。我们将其安装为开发依赖项，这意味着如果您打算将项目作为库发布到NPM 本身，则不会包含 TypeScript ：

NPM is Node’s package manager. It comes with a CLI, a registry, and other tools that allow you to install dependencies. Once you initialize your package.json, install TypeScript from NPM. We install it as a development dependency, meaning that TypeScript won’t be included if you intend to publish your project as a library to NPM itself:

$  npm  install  -D  typescript

$ npm install -D typescript

您可以全局安装 TypeScript，这样 TypeScript 编译器就可以在任何地方使用，但我强烈建议每个项目单独安装 TypeScript。根据您访问项目的频率，您最终会得到与项目代码同步的不同 TypeScript 版本。全局安装（和更新）TypeScript 可能会破坏您有一段时间没碰过的项目。

You can globally install TypeScript so you have the TypeScript compiler available everywhere, but I strongly suggest installing TypeScript separately per project. Depending on how frequently you visit your projects, you will end up with different TypeScript versions that are in sync with your project’s code. Installing (and updating) TypeScript globally might break projects you haven’t touched in a while.

现在 TypeScript 已安装完毕，请初始化一个新的 TypeScript 项目。为此，请使用 NPX：它允许您执行相对于项目安装的命令行实用程序。

Now that TypeScript is installed, initialize a new TypeScript project. Use NPX for that: it allows you to execute a command-line utility that you installed relative to your project.

和：

With:

$  npx  tsc—— 初始化

$ npx tsc --init

您可以运行项目的本地版本的 TypeScript 编译器并传递init标志来创建一个新的tsconfig.json。

you can run your project’s local version of the TypeScript compiler and pass the init flag to create a new tsconfig.json.

tsconfig.json是 TypeScript 项目的主要配置文件。它包含所需的所有配置，以便 TypeScript 了解如何解释代码、如何使类型可用于依赖项，以及是否需要打开或关闭某些功能。

The tsconfig.json is the main configuration file for your TypeScript project. It contains all the configuration needed so that TypeScript understands how to interpret your code, how to make types available for dependencies, and if you need to turn certain features on or off.

默认情况下，TypeScript 为您设置以下选项：

Per default, TypeScript sets these options for you:

{
  "compilerOptions": {
    "target": "es2016",
    "module": "commonjs",
    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true,
    "strict": true,
    "skipLibCheck": true
  }
}

{
  "compilerOptions": {
    "target": "es2016",
    "module": "commonjs",
    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true,
    "strict": true,
    "skipLibCheck": true
  }
}

让我们详细地看一下。

Let’s look at them in detail.

target是es2016，这意味着如果你运行 TypeScript 编译器，它会将你的 TypeScript 文件编译为与 ECMAScript 2016 兼容的语法。根据你支持的浏览器或环境，你可以将其设置为较新的版本（ECMAScript 版本以发布年份命名）或较旧的版本，例如es5对于必须支持非常旧的 Internet Explorer 版本的人。当然，我希望你不必这样做。

target is es2016, which means that if you run the TypeScript compiler, it will compile your TypeScript files to an ECMAScript 2016 compatible syntax. Depending on your supported browsers or environments, you can set that either to something more recent (ECMAScript versions are named after the year of release) or to something older such as es5 for people who have to support very old Internet Explorer versions. Of course, I hope you don’t have to.

module是commonjs。这允许您编写 ECMAScript 模块语法，但 TypeScript 不会将此语法带到输出，而是将其编译为 CommonJS 格式。这意味着：

module is commonjs. This allows you to write ECMAScript module syntax, but instead of carrying this syntax over to the output, TypeScript will compile it to the CommonJS format. This means that:

import { name } from "./my-module";

console.log(name);
//...

import { name } from "./my-module";

console.log(name);
//...

变成：

becomes:

const my_module_1 = require("./my-module");
console.log(my_module_1.name);

const my_module_1 = require("./my-module");
console.log(my_module_1.name);

一旦编译完成。CommonJS 是 Node.js 的模块系统，由于 Node 的流行，它变得非常普遍。Node.js 也采用了 ECMAScript 模块，我们将在1.9 节中讨论这个问题。

once you compile. CommonJS was the module system for Node.js and has become very common because of Node’s popularity. Node.js has since adopted ECMAScript modules as well, something we’ll tackle in Recipe 1.9.

esModuleInterop确保非 ECMAScript 模块在导入后与标准保持一致。forceConsistentCasingInFileNames帮助使用区分大小写的文件系统的人与使用不区分大小写的文件系统的人合作。并skipLibCheck假设您安装的类型定义文件（稍后会详细介绍）没有错误。因此您的编译器不会检查它们，并且会变得更快一些。

esModuleInterop ensures modules that aren’t ECMAScript modules are aligned to the standard once imported. forceConsistentCasingInFileNames helps people using case-sensitive file systems cooperate with folks who use case-insensitive file systems. And skipLibCheck assumes that your installed type definition files (more on that later) have no errors. So your compiler won’t check them and will become a little faster.

最有趣的功能之一是 TypeScript 的严格模式。如果设置为true，TypeScript 将在某些领域表现不同。这是 TypeScript 团队定义类型系统应如何表现的一种方式。

One of the most interesting features is TypeScript’s strict mode. If set to true, TypeScript will behave differently in certain areas. It’s a way for the TypeScript team to define their view on how the type system should behave.

如果 TypeScript 因类型系统视图发生变化而引入重大更改，它将被纳入严格模式。这最终意味着，如果您更新 TypeScript 并始终在严格模式下运行，您的代码可能会崩溃。

If TypeScript introduces a breaking change because the view on the type system changes, it will get incorporated in strict mode. This ultimately means that your code might break if you update TypeScript and always run in strict mode.

为了让你有时间适应变化，TypeScript 还允许您逐个打开或关闭某些严格模式功能。

To give you time to adapt to changes, TypeScript also allows you to turn certain strict mode features on or off, feature by feature.

除了默认设置外，我强烈建议另外设置两个：

In addition to the default settings, I strongly recommend two more:

{
  "compilerOptions": {
    //...
    "rootDir": "./src",
    "outDir": "./dist"
  }
}

{
  "compilerOptions": {
    //...
    "rootDir": "./src",
    "outDir": "./dist"
  }
}

这告诉 TypeScript 从src文件夹中获取源文件，并将编译后的文件放入dist文件夹中。此设置允许您将构建的文件与您编写的文件分开。当然，您必须创建src文件夹； dist文件夹将在编译后创建。

This tells TypeScript to pick up source files from a src folder and put the compiled files into a dist folder. This setup allows you to separate your built files from the ones you author. You will have to create the src folder, of course; the dist folder will be created after you compile.

哦，编译。设置好项目后，在以下位置创建一个index.ts文件src：

Oh, compilation. Once you have your project set up, create an index.ts file in src:

console.log("Hello World");

console.log("Hello World");

.ts扩展名表示这是一个 TypeScript 文件。现在运行：

The .ts extension indicates it’s a TypeScript file. Now run:

$  npx  tsc

$ npx tsc

在命令行中查看编译器的工作情况。

in your command line and see the compiler at work.

问题

Problem

您希望编写常规 JavaScript，无需额外的构建步骤，但仍能获得一些编辑器支持和函数的正确类型信息。但是，您不想使用 JSDoc 定义复杂的对象类型，如方案 1.1所示。

You want to write regular JavaScript with no extra build step but still get some editor support and proper type information for your functions. However, you don’t want to define your complex object types with JSDoc as shown in Recipe 1.1.

解决方案

Solution

将类型定义文件“放在一边”，并以“检查 JavaScript”模式运行 TypeScript 编译器。

Keep type definition files “on the side” and run the TypeScript compiler in the “check JavaScript” mode.

讨论

Discussion

逐步采用一直是 TypeScript 的专门目标。借助这种我称之为“侧面类型”的技术，您可以为对象类型和泛型和条件类型等高级功能编写 TypeScript 语法（参见第 5 章），而不必使用笨重的 JSDoc 注释，但您仍可以为实际应用编写 JavaScript。

Gradual adoption has always been a dedicated goal for TypeScript. With this technique, which I dubbed “types on the side,” you can write TypeScript syntax for object types and advanced features like generics and conditional types (see Chapter 5) instead of clunky JSDoc comments, but you still write JavaScript for your actual app.

在项目的某个地方（可能是@types文件夹），创建一个类型定义文件。它的后缀是.d.ts，与常规.ts文件不同，它的目的是保存声明，而不是实际代码。

Somewhere in your project, maybe in a @types folder, create a type definition file. Its ending is .d.ts, and as opposed to regular .ts files, its purpose is to hold declarations but no actual code.

您可以在此处编写接口、类型别名和复杂类型：

This is where you can write your interfaces, type aliases, and complex types:

// @types/person.d.ts

// An interface for objects of this shape
export interface Person {
  name: string;
  age: number;
}

// An interface that extends the original one
// this is tough to write with JSDoc comments alone.
export interface Student extends Person {
  semester: number;
}

// @types/person.d.ts

// An interface for objects of this shape
export interface Person {
  name: string;
  age: number;
}

// An interface that extends the original one
// this is tough to write with JSDoc comments alone.
export interface Student extends Person {
  semester: number;
}

请注意，您从声明文件中导出接口。这样您就可以将它们导入到 JavaScript 文件中：

Note that you export the interfaces from the declaration files. This is so you can import them in your JavaScript files:

// index.js
/** @typedef { import ("../@types/person").Person } Person */

// index.js
/** @typedef { import ("../@types/person").Person } Person */

第一行的注释告诉 TypeScriptPerson从@types/person导入类型并以名称提供Person。

The comment on the first line tells TypeScript to import the Person type from @types/person and make it available under the name Person.

现在，您可以使用该标识符来注释函数参数或对象，就像使用原始类型一样string：

Now you can use this identifier to annotate function parameters or objects just like you would with primitive types like string:

// index.js, continued

/**
 * @param {Person} person
 */
function printPerson(person) {
  console.log(person.name);
}

// index.js, continued

/**
 * @param {Person} person
 */
function printPerson(person) {
  console.log(person.name);
}

为了确保获得编辑器反馈，你仍然需要@ts-check在 JavaScript 文件的开头进行设置，如方案 1.1中所述。或者，你可以将项目配置为始终检查 JavaScript。

To make sure that you get editor feedback, you still need to set @ts-check at the beginning of your JavaScript files as described in Recipe 1.1. Or, you can configure your project to always check JavaScript.

打开tsconfig.json并将checkJs标志设置为。这将从srctrue文件夹中获取所有 JavaScript 文件，并在编辑器中不断为您提供有关类型错误的反馈。您还可以运行以查看命令行中是否有错误。npx tsc

Open tsconfig.json and set the checkJs flag to true. This will pick up all the JavaScript files from your src folder and give you constant feedback on type errors in your editor. You also can run npx tsc to see if you have errors in your command line.

如果你不希望 TypeScript 将你的 JavaScript 文件转换为旧版本的 JavaScript，请确保设置noEmit为true：

If you don’t want TypeScript to transpile your JavaScript files to older versions of JavaScript, make sure you set noEmit to true:

{
  "compilerOptions": {
    "checkJs": true,
    "noEmit": true,
  }
}

{
  "compilerOptions": {
    "checkJs": true,
    "noEmit": true,
  }
}

这样，TypeScript 将查看你的源文件并为你提供所需的所有类型信息，但它不会触及你的代码。

With that, TypeScript will look at your source files and will give you all the type information you need, but it won’t touch your code.

这种技术也以可扩展性而闻名。Preact 等著名 JavaScript 库就是这样工作的，并为其用户和贡献者提供了出色的工具。

This technique is also known to scale. Prominent JavaScript libraries like Preact work like this and provide fantastic tooling for their users as well as their contributors.

问题

Problem

您希望让您的项目充分利用 TypeScript，但您需要迁移整个代码库。

You want to get the full benefits of TypeScript for your project, but you need to migrate an entire codebase.

解决方案

Solution

将模块文件从.js重命名为.ts。使用多个编译器选项和功能来帮助您消除错误。

Rename your modules file by file from .js to .ts. Use several compiler options and features that help you iron out errors.

讨论

Discussion

使用 TypeScript 文件而不是具有类型的 JavaScript 文件的好处是，您的类型和实现都在一个文件中，这为您提供了更好的编辑器支持和对更多 TypeScript 功能的访问，并提高了与其他工具的兼容性。

The benefit of having TypeScript files instead of JavaScript files with types is that your types and implementations are in one file, which gives you better editor support and access to more TypeScript features, and increases compatibility with other tools.

但是，将所有文件从.js重命名为.ts很可能会导致大量错误。这就是为什么你应该逐个文件进行操作并逐步提高类型安全性。

However, just renaming all files from .js to .ts most likely will result in tons of errors. This is why you should go file by file and gradually increase type safety as you go along.

迁移时最大的问题是你突然要处理 TypeScript 项目，而不是 JavaScript。不过，你的许多模块都是 JavaScript，如果没有类型信息，它们将无法通过类型检查步骤。

The biggest problem when migrating is that you’re suddenly dealing with a TypeScript project, not with JavaScript. Still, lots of your modules will be JavaScript and, with no type information, they will fail the type-checking step.

通过关闭 JavaScript 的类型检查，让您自己和 TypeScript 更容易，但允许 TypeScript 模块加载和引用 JavaScript 文件：

Make it easier for yourself and for TypeScript by turning off type-checking for JavaScript, but allow TypeScript modules to load and refer to JavaScript files:

{
  "compilerOptions": {
    "checkJs": false,
    "allowJs": true
  }
}

{
  "compilerOptions": {
    "checkJs": false,
    "allowJs": true
  }
}

现在运行npx tsc，你会看到 TypeScript 会获取源文件夹中的所有 JavaScript 和 TypeScript 文件，并在目标文件夹中创建相应的 JavaScript 文件。TypeScript 还会转译你的代码，使其与指定的目标版本兼容。

Should you run npx tsc now, you will see that TypeScript picks up all JavaScript and TypeScript files in your source folder and creates respective JavaScript files in your destination folder. TypeScript will also transpile your code to be compatible with the specified target version.

如果你正在使用依赖项，你会发现其中一些依赖项没有类型信息。这也会产生 TypeScript 错误：

If you are working with dependencies, you will see that some of them don’t come with type information. This will also produce TypeScript errors:

import _ from "lodash";
//            ^- Could not find a declaration
//               file for module 'lodash'.

import _ from "lodash";
//            ^- Could not find a declaration
//               file for module 'lodash'.

安装第三方类型定义可以解决此错误。请参阅方案 1.5。

Install third-party type definitions to get rid of this error. See Recipe 1.5.

一旦你逐个文件地迁移，你可能会意识到你无法一次性获得一个文件的所有类型。存在依赖关系，你很快就会陷入困境：有太多文件需要调整，然后你才能处理你真正需要的文件。

Once you migrate file by file, you might realize that you won’t be able to get all typings for one file in one go. There are dependencies, and you will quickly go down the rabbit hole of having too many files to adjust before you can tackle the one that you actually need.

你始终可以选择忍受错误。默认情况下，TypeScript 将编译器选项设置noEmitOnError为false：

You can always decide just to live with the error. By default, TypeScript sets the compiler option noEmitOnError to false:

{
  "compilerOptions": {
    "noEmitOnError": false
  }
}

{
  "compilerOptions": {
    "noEmitOnError": false
  }
}

这意味着无论你的项目中有多少错误，TypeScript 都会生成结果文件，尽量不阻碍你。这可能是你在完成迁移后想要打开的设置。

This means that no matter how many errors you have in your project, TypeScript will generate result files, trying not to block you. This might be a setting you want to turn on after you finish migrating.

在严格模式下，TypeScript 的功能标志noImplicitAny设置为true。此标志将确保您不会忘记为变量、常量或函数参数分配类型。即使只是any：

In strict mode, TypeScript’s feature flag noImplicitAny is set to true. This flag will make sure that you don’t forget to assign a type to a variable, constant, or function parameter. Even if it’s just any:

function printPerson(person: any) {
  // This doesn't make sense, but is ok with any
  console.log(person.gobbleydegook);
}

// This also doesn't make sense, but any allows it
printPerson(123);

function printPerson(person: any) {
  // This doesn't make sense, but is ok with any
  console.log(person.gobbleydegook);
}

// This also doesn't make sense, but any allows it
printPerson(123);

any是 TypeScript 中的万能类型。每个值都与 兼容any，并any允许您访问每个属性或调用每个方法。any有效地关闭类型检查，让您在迁移过程中有喘息的空间。

any is the catchall type in TypeScript. Every value is compatible with any, and any allows you to access every property or call every method. any effectively turns off type-checking, giving you some room to breathe during your migration process.

或者，你可以用 注释你的参数unknown。这也允许你将所有内容传递给函数，但在你了解更多类型之前，不允许你对其执行任何操作。

Alternatively, you can annotate your parameters with unknown. This also allows you to pass everything to a function but won’t allow you to do anything with it until you know more about the type.

@ts-ignore您还可以通过在要排除类型检查的行前添加注释来决定忽略错误。@ts-nocheck文件开头的注释将完全关闭此特定模块的类型检查。

You can also decide to ignore errors by adding a @ts-ignore comment before the line you want to exclude from type-checking. A @ts-nocheck comment at the beginning of your file turns off type-checking entirely for this particular module.

对于迁移来说，一个非常棒的注释指令是@ts-expect-error。它的工作原理是@ts-ignore，它会吞掉类型检查过程中的错误，但如果没有发现类型错误，则会生成红色波浪线。

A comment directive that is fantastic for migration is @ts-expect-error. It works like @ts-ignore as it will swallow errors from the type-checking progress but will produce red squiggly lines if no type error is found.

迁移时，这可以帮助您找到已成功移动到 TypeScript 的位置。当没有@ts-expect-error剩余指令时，您就完成了：

When migrating, this helps you find the spots that you successfully moved to TypeScript. When there are no @ts-expect-error directives left, you’re done:

function printPerson(person: Person) {
  console.log(person.name);
}

// This error will be swallowed
// @ts-expect-error
printPerson(123);


function printNumber(nr: number) {
  console.log(nr);
}

// v- Unused '@ts-expect-error' directive.ts(2578)
// @ts-expect-error
printNumber(123);

function printPerson(person: Person) {
  console.log(person.name);
}

// This error will be swallowed
// @ts-expect-error
printPerson(123);


function printNumber(nr: number) {
  console.log(nr);
}

// v- Unused '@ts-expect-error' directive.ts(2578)
// @ts-expect-error
printNumber(123);

这种技术的优点在于你可以调换职责。通常，你必须确保将正确的值传递给函数；现在你可以确保函数能够处理正确的输入。

The great thing about this technique is that you flip responsibilities. Usually, you have to make sure that you pass in the right values to a function; now you can make sure that the function is able to handle the right input.

在整个迁移过程中消除错误的所有可能性都有一个共同点：它们都是明确的。您需要明确设置@ts-expect-error注释、将函数参数注释为any，或完全忽略文件进行类型检查。这样，您就可以在迁移过程中始终搜索这些逃生舱，并确保随着时间的推移，您已经摆脱了所有错误。

All possibilities for getting rid of errors throughout your migration process have one thing in common: they’re explicit. You need to explicitly set @ts-expect-error comments, annotate function parameters as any, or ignore files entirely from type-checking. With that, you can always search for those escape hatches during the migration process and make sure that, over time, you got rid of them all.

问题

Problem

您依赖于尚未用 TypeScript 编写的依赖项，因此缺少类型。

You rely on a dependency that hasn’t been written in TypeScript and therefore lacks typings.

解决方案

Solution

从Definitely Typed安装社区维护的类型定义。

From Definitely Typed, install community-maintained type definitions.

讨论

Discussion

Definitely Typed 是 GitHub 上最大的、最活跃的存储库之一，收集了由社区开发和维护的高质量 TypeScript 类型定义 。

Definitely Typed is one of the biggest and most active repositories on GitHub and collects high-quality TypeScript type definitions developed and maintained by the community.

维护的类型定义数量接近10,000个，并且很少有JavaScript库不可用。

The number of maintained type definitions is close to 10,000, and there is rarely a JavaScript library not available.

所有类型定义都经过了 lint 和检查，并部署到命名空间下的 Node.js 包注册表 NPM 中。NPM 在每个包的信息站点上都有一个指示器，显示是否提供 Definitely Typed 类型定义，如图1-2@types所示。

All type definitions are linted, checked, and deployed to the Node.js package registry NPM under the @types namespace. NPM has an indicator on each package’s information site that shows if Definitely Typed type definitions are available, as you can see in Figure 1-2.

图 1-2。React的 NPM 站点在包名称旁边显示了 DT 徽标；这 表示Definitely Typed 提供了类型定义

单击此徽标将带您进入类型定义的实际站点。如果某个软件包已经有第一方类型定义，则会在软件包名称旁边显示一个小的 TS 徽标，如图1-3所示。

Clicking on this logo leads you to the actual site for type definitions. If a package has first-party type definitions already available, it shows a small TS logo next to the package name, as shown in Figure 1-3.

图 1-3. Definitely Typed 中 React 的类型定义

例如，要安装流行的 JavaScript 框架 React 的类型，可以将@types/react包安装到本地依赖项中：

To install, for example, typings for the popular JavaScript framework React, you install the @types/react package to your local dependencies:

# Installing React
$  npm  install  --save  react

# Installing Type Definitions
$  npm  install  --save-dev  @types/react

# Installing React
$ npm install --save react

# Installing Type Definitions
$ npm install --save-dev @types/react

默认情况下，TypeScript 将拾取它能找到的、位于相对于项目根文件夹的可见@types文件夹中的类型定义。它还将拾取来自node_modules/@types的所有类型定义；请注意，这是 NPM 安装的位置，例如 。@types/react

By default, TypeScript will pick up type definitions it can find that are in visible @types folders relative to your project’s root folder. It will also pick up all type definitions from node_modules/@types; note that this is where NPM installs, for example, @types/react.

我们这样做是因为tsconfig.jsontypeRoots中的编译器选项设置为和。如果您需要覆盖此设置，请确保包含原始文件夹（如果您想从 Definitely Typed 中获取类型定义）：@types./node_modules/@types

We do this because the typeRoots compiler option in tsconfig.json is set to @types and ./node_modules/@types. Should you need to override this setting, make sure to include the original folders if you want to pick up type definitions from Definitely Typed:

{
  "compilerOptions": {
    "typeRoots": ["./typings", "./node_modules/@types"]
  }
}

{
  "compilerOptions": {
    "typeRoots": ["./typings", "./node_modules/@types"]
  }
}

请注意，只需将类型定义安装到node_modules/@types中，TypeScript 就会在编译期间加载它们。这意味着如果某些类型声明了全局变量，TypeScript 就会选择它们。

Note that just by installing type definitions into node_modules/@types, TypeScript will load them during compilation. This means that if some types declare globals, TypeScript will pick them up.

您可能希望通过types在编译器选项的设置中指定哪些包应该被允许对全局范围做出贡献：

You might want to explicitly state which packages should be allowed to contribute to the global scope by specifying them in the types setting in your compiler options:

{
  "compilerOptions": {
    "types": ["node", "jest"]
  }
}

{
  "compilerOptions": {
    "types": ["node", "jest"]
  }
}

请注意，此设置只会影响对全局范围的贡献。如果通过 import 语句加载节点模块，TypeScript 仍将从@types中选择正确的类型：

Note that this setting will only affect the contributions to the global scope. If you load node modules via import statements, TypeScript still will pick up the correct types from @types:

// If `@types/lodash` is installed, we get proper
// type defintions for this NPM package
import _ from "lodash"

const result = _.flattenDeep([1, [2, [3, [4]], 5]]);

// If `@types/lodash` is installed, we get proper
// type defintions for this NPM package
import _ from "lodash"

const result = _.flattenDeep([1, [2, [3, [4]], 5]]);

我们将在方案 1.7中再次讨论此设置。

We will revisit this setting in Recipe 1.7.

问题

Problem

您想要编写一个针对 Node.js 和浏览器并具有共享依赖项的全栈应用程序。

You want to write a full-stack application targeting Node.js and the browser, with shared dependencies.

解决方案

Solution

为每个前端和后端创建两个tsconfig文件，并将共享 依赖项作为复合文件加载。

Create two tsconfig files for each frontend and backend, and load shared dependencies as composites.

讨论

Discussion

Node.js 和浏览器都运行 JavaScript，但它们对开发人员应该如何处理环境的理解截然不同。Node.js 适用于服务器、命令行工具以及所有无需 UI 即可运行的东西——无头。它有自己的一套 API 和标准库。这个小脚本启动一个 HTTP 服务器：

Node.js and the browser both run JavaScript, but they have a very different understanding of what developers should do with the environment. Node.js is meant for servers, command-line tools, and everything that runs without a UI—headless. It has its own set of APIs and standard library. This little script starts an HTTP server:

const http = require('http'); 

const hostname = '127.0.0.1';
const port = process.env.PORT || 3000; 

const server = http.createServer((req, res) => {
  res.statusCode = 200;
  res.setHeader('Content-Type', 'text/plain');
  res.end('Hello World');
});

server.listen(port, hostname, () => {
  console.log(`Server running at http://${hostname}:${port}/`); 
});

const http = require('http'); 

const hostname = '127.0.0.1';
const port = process.env.PORT || 3000; 

const server = http.createServer((req, res) => {
  res.statusCode = 200;
  res.setHeader('Content-Type', 'text/plain');
  res.end('Hello World');
});

server.listen(port, hostname, () => {
  console.log(`Server running at http://${hostname}:${port}/`); 
});

虽然毫无疑问它是 JavaScript，但 Node.js 也有一些独有的东西：

While it’s without a doubt JavaScript, some things are unique to Node.js:

"http"是 Node.js 内置的模块，用于处理与 HTTP 相关的所有内容。它通过 加载require，这是 Node 模块系统CommonJS的一个指标。在 Node.js 中还有其他加载模块的方法，如我们在1.9 节中看到的那样，但最近 CommonJS 是最常见的。

"http" is a built-in Node.js module for everything related to HTTP. It is loaded via require, which is an indicator for Node’s module system called CommonJS. There are other ways to load modules in Node.js as we see in Recipe 1.9, but recently CommonJS has been the most common.

该process对象是一个全局对象，包含有关环境变量和当前 Node.js 进程的一般信息。这也是 Node.js 所独有的。

The process object is a global object containing information on environment variables and the current Node.js process in general. This is also unique to Node.js.

及其函数console几乎在每个 JavaScript 运行时中都可用，但它在 Node 中的作用与在浏览器中的作用不同。在 Node 中，它会在 STDOUT 上打印；在浏览器中，它会将一行打印到开发工具中。

The console and its functions are available in almost every JavaScript runtime, but what it does in Node is different from what it does in the browser. In Node, it prints on STDOUT; in the browser, it will print a line to the development tools.

当然，Node.js 还有更多独特的 API。但浏览器中的 JavaScript 也是如此：

There are of course many more unique APIs for Node.js. But the same goes for JavaScript in the browser:

import { msg } from `./msg.js`; 

document.querySelector('button')?.addEventListener("click", () => { 
  console.log(msg); 
});

import { msg } from `./msg.js`; 

document.querySelector('button')?.addEventListener("click", () => { 
  console.log(msg); 
});

多年来，ECMAScript 模块一直没有办法加载模块，现在终于进入了 JavaScript 和浏览器。这行代码从另一个 JavaScript 模块加载一个对象。它以原生方式在浏览器中运行，是 Node.js 的第二个模块系统（参见方案 1.9）。

After years without a way to load modules, ECMAScript modules have found their way into JavaScript and the browsers. This line loads an object from another JavaScript module. This runs in the browser natively and is a second module system for Node.js (see Recipe 1.9).

浏览器中的 JavaScript 旨在与 UI 事件交互。指向文档对象模型 (DOM)document中的元素的对象和概念是浏览器独有的。添加事件侦听器并侦听“点击”事件也是如此。Node.js 中没有这个。querySelector

JavaScript in the browser is meant to interact with UI events. The document object and the idea of a querySelector that points to elements in the Document Object Model (DOM) are unique to the browser. So is adding an event listener and listening on “click” events. You don’t have this in Node.js.

再说一遍console，它具有与 Node.js 相同的 API，但结果略有 不同。

And again, console. It has the same API as in Node.js, but the result is a bit different.

差异如此之大，很难创建一个可以同时处理这两个部分的 TypeScript 项目。如果您正在编写全栈应用程序，则需要创建两个 TypeScript 配置文件来处理堆栈的每个部分。

The differences are so big, it’s hard to create one TypeScript project that handles both. If you are writing a full-stack application, you need to create two TypeScript configuration files that deal with each part of your stack.

我们先来处理后端。假设你想用 Node.js 编写一个 Express.js 服务器（Express 是 Node 的一个流行服务器框架）。首先，创建一个新的 NPM 项目，如方案 1.1所示。然后，安装 Express 作为依赖项：

Let’s work on the backend first. Let’s assume you want to write an Express.js server in Node.js (Express is a popular server framework for Node). First, you create a new NPM project as shown in Recipe 1.1. Then, install Express as a dependency:

$  npm  install  --save  express

$ npm install --save express

并从 Definitely Typed 安装 Node.js 和 Express 的类型定义：

And install type definitions for Node.js and Express from Definitely Typed:

$  npm  install  -D  @types/express  @types/node

$ npm install -D @types/express @types/node

创建一个名为server 的新文件夹。这是您的 Node.js 代码所在的位置。不要通过 创建新的tsconfig.json ，而是在项目的servertsc文件夹中创建新的tsconfig.json。以下是内容：

Create a new folder called server. This is where your Node.js code goes. Instead of creating a new tsconfig.json via tsc, create a new tsconfig.json in your project’s server folder. Here are the contents:

// server/tsconfig.json
{
  "compilerOptions": {
    "target": "ESNext",
    "lib": ["ESNext"],
    "module": "commonjs",
    "rootDir": "./",
    "moduleResolution": "node",
    "types": ["node"],
    "outDir": "../dist/server",
    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true,
    "strict": true,
    "skipLibCheck": true
  }
}

// server/tsconfig.json
{
  "compilerOptions": {
    "target": "ESNext",
    "lib": ["ESNext"],
    "module": "commonjs",
    "rootDir": "./",
    "moduleResolution": "node",
    "types": ["node"],
    "outDir": "../dist/server",
    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true,
    "strict": true,
    "skipLibCheck": true
  }
}

你应该已经了解了很多，但有几件事特别突出：

You should already know a lot of this, but a few things stand out:

• 该module属性设置为commonjs，即原始 Node.js 模块系统。所有import和export语句都将转换为其 CommonJS 对应项。

• The module property is set to commonjs, the original Node.js module system. All import and export statements will be transpiled to their CommonJS counterpart.

• 属性types设置为["node"]。此属性包括您希望全局可用的所有库。如果"node"处于全局范围内，您将获得require、process和全局空间中的其他 Node.js 细节的类型信息。

• The types property is set to ["node"]. This property includes all the libraries you want to have globally available. If "node" is in the global scope, you will get type information for require, process, and other Node.js specifics that are in the global space.

要编译服务器端代码，请运行：

To compile your server-side code, run:

$  npx  tsc  -p 服务器/tsconfig.json

$ npx tsc -p server/tsconfig.json

现在对于客户端来说：

Now for the client:

// client/tsconfig.json
{
  "compilerOptions": {
    "target": "ESNext",
    "lib": ["DOM", "ESNext"],
    "module": "ESNext",
    "rootDir": "./",
    "moduleResolution": "node",
    "types": [],
    "outDir": "../dist/client",
    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true,
    "strict": true,
    "skipLibCheck": true
  }
}

// client/tsconfig.json
{
  "compilerOptions": {
    "target": "ESNext",
    "lib": ["DOM", "ESNext"],
    "module": "ESNext",
    "rootDir": "./",
    "moduleResolution": "node",
    "types": [],
    "outDir": "../dist/client",
    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true,
    "strict": true,
    "skipLibCheck": true
  }
}

有一些相似之处，但同样，有几点很突出：

There are some similarities, but again, a few things stand out:

• 您添加DOM到lib属性中。这为您提供了与浏览器相关的所有内容的类型定义。您需要通过 Definitely Typed 安装 Node.js 类型，而 TypeScript 会随编译器一起提供浏览器的最新类型定义。

• You add DOM to the lib property. This gives you type definitions for everything related to the browser. Where you needed to install Node.js typings via Definitely Typed, TypeScript ships the most recent type definitions for the browser with the compiler.

• 数组types为空。这将从我们的全局类型中删除 "node"。由于您只能为每个package.json安装类型定义，因此"node"我们之前安装的类型定义将在整个代码库中可用。 client但是，对于部分，您想摆脱它们。

• The types array is empty. This will remove "node" from our global typings. Since you only can install type definitions per package.json, the "node" type definitions we installed earlier would be available in the entire code base. For the client part, however, you want to get rid of them.

要编译前端代码，请运行：

To compile your frontend code, run:

$  npx  tsc  -p 客户端/tsconfig.json

$ npx tsc -p client/tsconfig.json

请注意，您配置了两个不同的tsconfig.json文件。Visual Studio Code 等编辑器仅获取每个文件夹中tsconfig.json文件的配置信息。您也可以将它们命名为tsconfig.server.json和tsconfig.client.json，并将它们放在项目的根文件夹中（并调整所有目录属性）。tsc将使用正确的配置并在发现任何错误时抛出错误，但编辑器将主要保持静默或使用默认配置。

Please note that you configured two distinct tsconfig.json files. Editors like Visual Studio Code pick up configuration information only for tsconfig.json files per folder. You could as well name them tsconfig.server.json and tsconfig.client.json and have them in your project’s root folder (and adjust all directory properties). tsc will use the correct configurations and throw errors if it finds any, but the editor will mostly stay silent or work with a default configuration.

如果您想要共享依赖项，事情会变得有点复杂。实现共享依赖项的一种方法是使用项目引用和复合项目。这意味着您将共享代码提取到其自己的文件夹中，但告诉 TypeScript，这将是另一个项目的依赖项。

Things get a bit hairier if you want to have shared dependencies. One way to achieve shared dependencies is to use project references and composite projects. This means that you extract your shared code in its own folder, but tell TypeScript that this is meant to be a dependency project of another one.

在与客户端和服务端同级目录下创建一个共享文件夹，在共享文件夹中创建一个tsconfig.json 文件，内容如下：

Create a shared folder on the same level as client and server. Create a tsconfig.json in shared with these contents:

// shared/tsconfig.json
{
    "compilerOptions": {
      "composite": true,
      "target": "ESNext",
      "module": "ESNext",
      "rootDir": "../shared/",
      "moduleResolution": "Node",
      "types": [],
      "declaration": true,
      "outDir": "../dist/shared",
      "esModuleInterop": true,
      "forceConsistentCasingInFileNames": true,
      "strict": true,
      "skipLibCheck": true
    },
  }

// shared/tsconfig.json
{
    "compilerOptions": {
      "composite": true,
      "target": "ESNext",
      "module": "ESNext",
      "rootDir": "../shared/",
      "moduleResolution": "Node",
      "types": [],
      "declaration": true,
      "outDir": "../dist/shared",
      "esModuleInterop": true,
      "forceConsistentCasingInFileNames": true,
      "strict": true,
      "skipLibCheck": true
    },
  }

有两件事再次引人注目：

Two things stand out again:

• 标志composite设置为true。这允许其他项目引用该项目。

• The flag composite is set to true. This allows other projects to reference this one.

• 该declaration标志也设置为true。这将从您的代码生成d.ts文件，以便其他项目可以使用类型信息。

• The declaration flag is also set to true. This will generate d.ts files from your code so other projects can consume type information.

要将它们包含在客户端和服务器代码中，请将这一行添加到client/tsconfig.json和server/tsconfig.json中：

To include them in your client and server code, add this line to client/tsconfig.json and server/tsconfig.json:

// server/tsconfig.json
// client/tsconfig.json
{
  "compilerOptions": {
    // Same as before
  },
  "references": [
    { "path": "../shared/tsconfig.json" }
  ]
}

// server/tsconfig.json
// client/tsconfig.json
{
  "compilerOptions": {
    // Same as before
  },
  "references": [
    { "path": "../shared/tsconfig.json" }
  ]
}

一切就绪。您可以编写共享依赖项并将其包含在 客户端和服务器代码中。

And you are all set. You can write shared dependencies and include them in your client and server code.

但是，有一个警告。如果您仅共享模型和类型信息，这种方法会很好用，但是一旦您共享实际功能，您就会发现两个不同的模块系统（Node 中的 CommonJS，浏览器中的 ECMAScript 模块）无法统一在一个编译文件中。您要么创建 ESNext 模块，但无法在 CommonJS 代码中导入它，要么创建 CommonJS 代码，但无法在浏览器中导入它。

There is a caveat, however. This works great if you share, for example, only models and type information, but the moment you share actual functionality, you will see that the two different module systems (CommonJS in Node, ECMAScript modules in the browser) can’t be unified in one compiled file. You either create an ESNext module and can’t import it in CommonJS code or create CommonJS code and can’t import it in the browser.

您可以做两件事：

There are two things you can do:

• 编译为 CommonJS 并让捆绑器负责浏览器的模块解析工作。

• Compile to CommonJS and let a bundler take care of the module resolution work for the browser.

• 编译为 ECMAScript 模块并基于 ECMAScript 模块编写现代 Node.js 应用程序。有关更多信息，请参阅范例 1.9 。

• Compile to ECMAScript modules and write modern Node.js applications based on ECMAScript modules. See Recipe 1.9 for more information.

由于您是新手，我强烈推荐第二种选择。

Since you are starting out new, I strongly recommend the second option.

问题

Problem

您想编写测试，但是测试框架的全局变量会干扰您的生产代码。

You want to write tests, but the globals for testing frameworks interfere with your production code.

解决方案

Solution

为开发和构建创建单独的tsconfig，并在后者中排除所有测试文件。

Create a separate tsconfig for development and build, and exclude all test files in the latter one.

讨论

Discussion

在 JavaScript 和 Node.js 生态系统中，有很多单元测试框架和测试运行器。它们在细节上各不相同，有不同的观点，或针对特定需求量身定制。其中一些可能比其他的更漂亮。

In the JavaScript and Node.js ecosystem, there are a lot of unit testing frameworks and test runners. They vary in detail, have different opinions, or are tailored for certain needs. Some of them might just be prettier than others.

虽然像Ava这样的测试运行器依赖于导入模块来将框架纳入范围，但其他测试运行器提供了一组全局变量。以Mocha为例：

While test runners like Ava rely on importing modules to get the framework into scope, others provide a set of globals. Take Mocha, for example:

import assert from "assert";
import { add } from "..";

describe("Adding numbers", () => {
  it("should add two numbers", () => {
    assert.equal(add(2, 3), 5);
  });
});

import assert from "assert";
import { add } from "..";

describe("Adding numbers", () => {
  it("should add two numbers", () => {
    assert.equal(add(2, 3), 5);
  });
});

assert来自 Node.js 内置断言库，但describe、it和更多都是 Mocha 提供的全局变量。它们也仅在 Mocha CLI 运行时存在。

assert comes from the Node.js built-in assertion library, but describe, it, and many more are globals provided by Mocha. They also only exist when the Mocha CLI is running.

这对您的类型设置带来了一些挑战，因为这些功能对于编写测试是必要的，但在您执行实际应用程序时不可用。

This provides a bit of a challenge for your type setup, as those functions are necessary to write tests but aren’t available when you execute your actual application.

解决方案是创建两个不同的配置文件：一个常规的tsconfig.json，用于开发，你的编辑器可以选择它（记住配方 1.6），还有一个单独的tsconfig.build.json，当你想编译你的应用程序时使用。

The solution is to create two different configuration files: a regular tsconfig.json for development that your editor can pick up (remember Recipe 1.6) and a separate tsconfig.build.json that you use when you want to compile your application.

第一个包含您需要的所有全局变量，包括 Mocha 的类型；后者确保您的编译中不包含任何测试文件。

The first one includes all the globals you need, including types for Mocha; the latter makes sure no test file is included within your compilation.

让我们一步一步地进行。我们以 Mocha 为例，但其他提供全局变量的测试运行器（如Jest）的工作方式也相同。

Let’s go through this step by step. We look at Mocha as an example, but other test runners that provide globals like Jest work just the same way.

首先，安装 Mocha 及其类型：

First, install Mocha and its types:

$  npm  install  --save-dev  mocha  @types/mocha  @types/node

$ npm install --save-dev mocha @types/mocha @types/node

创建一个新的tsconfig.base.json。由于开发和构建之间的唯一区别在于要包含的文件集和激活的库，因此您希望将所有其他编译器设置放在一个文件中，以便两者重复使用。Node.js 应用程序的示例文件如下所示：

Create a new tsconfig.base.json. Since the only differences between development and build are the set of files to be included and the libraries activated, you want to have all the other compiler settings located in one file you can reuse for both. An example file for a Node.js application would look like this:

// tsconfig.base.json
{
  "compilerOptions": {
    "target": "esnext",
    "module": "commonjs",
    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true,
    "strict": true,
    "outDir": "./dist",
    "skipLibCheck": true
  }
}

// tsconfig.base.json
{
  "compilerOptions": {
    "target": "esnext",
    "module": "commonjs",
    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true,
    "strict": true,
    "outDir": "./dist",
    "skipLibCheck": true
  }
}

源文件应位于 src中；测试文件应位于相邻的文件夹test中。本指南中创建的设置还允许您在项目中的任何位置创建以.test.ts结尾的文件。

The source files should be located in src; test files should be located in an adjacent folder test. The setup you create in this recipe will also allow you to create files ending with .test.ts anywhere in your project.

使用基本开发配置创建一个新的tsconfig.json。此配置用于编辑器反馈和使用 Mocha 运行测试。您可以从tsconfig.base.json扩展基本设置，并告知 TypeScript 要选择哪些文件夹 进行编译：

Create a new tsconfig.json with your base development configuration. This one is used for editor feedback and for running tests with Mocha. You extend the basic settings from tsconfig.base.json and inform TypeScript which folders to pick up for compilation:

// tsconfig.json
{
  "extends": "./tsconfig.base.json",
  "compilerOptions": {
    "types": ["node", "mocha"],
    "rootDirs": ["test", "src"]
  }
}

// tsconfig.json
{
  "extends": "./tsconfig.base.json",
  "compilerOptions": {
    "types": ["node", "mocha"],
    "rootDirs": ["test", "src"]
  }
}

请注意，您添加了typesNode 和 Mocha。该types属性定义哪些全局变量可用，并且在开发设置中，您同时拥有这两个全局变量。

Note that you add types for Node and Mocha. The types property defines which globals are available and, in the development setting, you have both.

此外，您可能会发现在执行测试之前编译测试很麻烦。有一些快捷方式可以帮助您。例如，ts-node运行本地安装的 Node.js 并首先进行内存中 TypeScript 编译：

Additionally, you might find that compiling your tests before executing them is cumbersome. There are shortcuts to help you. For example, ts-node runs your local installation of Node.js and does an in-memory TypeScript compilation first:

$  npm  install  --save-dev  ts-node 
$  npx  mocha  -r  ts-node/register  tests/*.ts

$ npm install --save-dev ts-node
$ npx mocha -r ts-node/register tests/*.ts

设置好开发环境后，就到了构建环境。创建一个tsconfig.build.json。它看起来与tsconfig.json类似，但你会立即发现差异：

With the development environment set up, it’s time for the build environment. Create a tsconfig.build.json. It looks similar to tsconfig.json, but you will spot the difference right away:

// tsconfig.build.json
{
  "extends": "./tsconfig.base.json",
  "compilerOptions": {
    "types": ["node"],
    "rootDirs": ["src"]
  },
  "exclude": ["**/*.test.ts", "**/test/**"]
}

// tsconfig.build.json
{
  "extends": "./tsconfig.base.json",
  "compilerOptions": {
    "types": ["node"],
    "rootDirs": ["src"]
  },
  "exclude": ["**/*.test.ts", "**/test/**"]
}

除了更改types和之外rootDirs，您还可以定义要从类型检查和编译中排除哪些文件。您可以使用通配符模式来排除位于测试文件夹中以.test.ts结尾的所有文件。根据您的喜好，您还可以将.spec.ts或spec文件夹添加到此数组中。

In addition to changing types and rootDirs, you define which files to exclude from type-checking and compilation. You use wild-card patterns that exclude all files ending with .test.ts that are located in test folders. Depending on your taste, you can also add .spec.ts or spec folders to this array.

通过引用正确的 JSON 文件来编译您的项目：

Compile your project by referring to the right JSON file:

$  npx  tsc  -p  tsconfig.build.json

$ npx tsc -p tsconfig.build.json

您将看到在结果文件（位于dist）中看不到任何测试文件。此外，虽然您仍然可以访问describe和it编辑源文件，但如果您尝试编译，则会收到错误：

You will see that in the result files (located in dist), you won’t see any test file. Also, while you still can access describe and it when editing your source files, you will get an error if you try to compile:

$ npx tsc -p tsconfig.build.json

src/index.ts:5:1 - 错误 TS2593：找不到名称“describe”。
您需要为测试运行器安装类型定义吗？
尝试 `npm i --save-dev @types/jest` 或 `npm i --save-dev @types/mocha`
然后将“jest”或“mocha”添加到 tsconfig 中的类型字段。

5 describe("这不起作用", () => {})
  ~~~~~~~~


在 src/index.ts 中发现 1 个错误:5

$ npx tsc -p tsconfig.build.json

src/index.ts:5:1 - error TS2593: Cannot find name 'describe'.
Do you need to install type definitions for a test runner?
Try `npm i --save-dev @types/jest` or `npm i --save-dev @types/mocha`
and then add 'jest' or 'mocha' to the types field in your tsconfig.

5 describe("this does not work", () => {})
  ~~~~~~~~


Found 1 error in src/index.ts:5

如果你不喜欢在开发模式下污染你的全局变量，你可以选择与方案 1.6中类似的设置，但它不允许你在源文件旁边编写测试。

If you don’t like polluting your globals during development mode, you can choose a similar setup as in Recipe 1.6, but it won’t allow you to write tests adjacent to your source files.

最后，您始终可以选择适合模块系统的测试运行器。

Finally, you can always opt for a test runner that prefers the module system.

问题

Problem

您希望在没有捆绑器的情况下工作并使用浏览器的模块加载功能来为您的应用程序工作，但您仍然希望拥有所有的类型信息。

You want to work without bundlers and use the browser’s module-loading capabilities for your app, yet you still want to have all the type information.

解决方案

Solution

target在tsconfig的编译器选项module中设置并指向带有.js扩展名的模块。此外，通过 NPM 将类型安装到依赖项，并使用tsconfig中的属性告诉 TypeScript 在哪里查找类型：esnextpath

Set target and module in your tsconfig’s compiler options to esnext and point to your modules with a .js extension. In addition, install types to dependencies via NPM, and use the path property in your tsconfig to tell TypeScript where to look for types:

// tsconfig.json
{
  "compilerOptions": {
    "target": "esnext",
    "module": "esnext",
    "paths": {
      "https://esm.sh/lodash@4.17.21": [
        "node_modules/@types/lodash/index.d.ts"
      ]
    }
  }
}

// tsconfig.json
{
  "compilerOptions": {
    "target": "esnext",
    "module": "esnext",
    "paths": {
      "https://esm.sh/lodash@4.17.21": [
        "node_modules/@types/lodash/index.d.ts"
      ]
    }
  }
}

讨论

Discussion

现代浏览器支持开箱即用的模块加载。您无需将应用打包成一组较小的文件，而是可以直接使用原始 JavaScript 文件。

Modern browsers support module loading out of the box. Instead of bundling your app into a smaller set of files, you can use the raw JavaScript files directly.

内容分发网络 (CDN)（例如esm.sh、unpkg等）旨在将节点模块和 JavaScript 依赖项作为 URL 分发，以供本机 ECMAScript 模块加载使用。

Content Delivery Networks (CDNs) like esm.sh, unpkg, and others are designed to distribute node modules and JavaScript dependencies as URLs, consumable by native ECMAScript module loading.

通过适当的缓存和最先进的 HTTP，ECMAScript 模块成为应用程序的真正替代品。

With proper caching and state-of-the-art HTTP, ECMAScript modules become a real alternative for apps.

TypeScript 不包含现代打包器，因此无论如何你都需要安装一个额外的工具。但如果你决定先使用模块，那么在使用 TypeScript 时需要考虑一些事项。

TypeScript does not include a modern bundler, so you would need to install an extra tool anyway. But if you decide to go module first, there are a few things to consider when working with TypeScript.

您想要实现的是用 TypeScript 编写import和export语句，但保留模块加载语法并让浏览器处理模块解析：

What you want to achieve is to write import and export statements in TypeScript but preserve the module-loading syntax and let the browser handle module resolution:

// File module.ts
export const obj = {
  name: "Stefan",
};

// File index.ts
import { obj } from "./module";

console.log(obj.name);

// File module.ts
export const obj = {
  name: "Stefan",
};

// File index.ts
import { obj } from "./module";

console.log(obj.name);

为了实现这一点，告诉 TypeScript：

To achieve this, tell TypeScript to:

1. 编译为可以理解模块的 ECMAScript 版本

2. Compile to an ECMAScript version that understands modules

3. 使用 ECMAScript 模块语法进行模块代码生成

4. Use the ECMAScript module syntax for module code generation

更新tsconfig.json中的两个属性：

Update two properties in your tsconfig.json:

// tsconfig.json
{
  "compilerOptions": {
    "target": "esnext",
    "module": "esnext"
  }
}

// tsconfig.json
{
  "compilerOptions": {
    "target": "esnext",
    "module": "esnext"
  }
}

module告诉 TypeScript 如何转换 import 和 export 语句。默认将模块加载转换为 CommonJS，如方案 1.2所示。设置module为esnext将使用 ECMAScript 模块加载，从而保留语法。

module tells TypeScript how to transform import and export statements. The default converts module loading to CommonJS, as seen in Recipe 1.2. Setting module to esnext will use ECMAScript module loading and thus preserve the syntax.

target告诉 TypeScript 您想要将代码转译到的 ECMAScript 版本。每年都会发布一个包含新功能的新 ECMAScript 版本。设置target为esnext将始终以最新的 ECMAScript 版本为目标。

target tells TypeScript the ECMAScript version you want to transpile your code to. Once a year, there’s a new ECMAScript release with new features. Setting target to esnext will always target the latest ECMAScript version.

根据您的兼容性目标，您可能希望将此属性设置为与您想要支持的浏览器兼容的 ECMAScript 版本。这通常是带有年份的版本（例如es2015，，等）。ECMAScript 模块适用于从 1999 年起的每个版本。es2016如果您使用较旧的版本，您将无法在浏览器中本地加载 ECMAScript 模块。es2017es2015

Depending on your compatibility goals, you might want to set this property to the ECMAScript version compatible with the browsers you want to support. This is usually a version with a year (e.g. es2015, es2016, es2017, etc). ECMAScript modules work with every version from es2015 on. If you go for an older version, you won’t be able to load ECMAScript modules natively in the browser.

更改这些编译器选项已经做了一件重要的事情：它保持语法不变。一旦您想要运行代码，就会出现问题。

Changing these compiler options already does one important thing: it leaves the syntax intact. A problem occurs once you want to run your code.

通常，TypeScript 中的 import 语句指向没有扩展名的文件。你写import { obj } from "./module"，省略.ts。编译后，仍然缺少此扩展名。但浏览器需要一个扩展名才能真正指向相应的 JavaScript 文件。

Usually, import statements in TypeScript point to files without an extension. You write import { obj } from "./module", leaving out .ts. Once you compile, this extension is still missing. But the browser needs an extension to actually point to the respective JavaScript file.

解决方案：添加.js扩展名，即使你在开发时指向.ts文件。TypeScript 足够聪明，可以识别这一点：

The solution: Add a .js extension, even though you are pointing to a .ts file when you develop. TypeScript is smart enough to pick that up:

// index.ts

// This still loads types from 'module.ts', but keeps
// the reference intact once we compile it.
import { obj } from './module.js';

console.log(obj.name);

// index.ts

// This still loads types from 'module.ts', but keeps
// the reference intact once we compile it.
import { obj } from './module.js';

console.log(obj.name);

对于您的项目模块，这就是您所需要的全部！

For your project’s modules, that’s all you need!

当你想使用依赖项时，它会变得更加有趣。如果你使用原生应用，你可能想要从 CDN 加载模块，比如esm.sh：

It gets a lot more interesting when you want to use dependencies. If you go native, you might want to load modules from a CDN, like esm.sh:

import _ from "https://esm.sh/lodash@4.17.21"
//             ^- Error 2307

const result = _.flattenDeep([1, [2, [3, [4]], 5]]);

console.log(result);

import _ from "https://esm.sh/lodash@4.17.21"
//             ^- Error 2307

const result = _.flattenDeep([1, [2, [3, [4]], 5]]);

console.log(result);

TypeScript 将出现以下错误信息：“找不到模块…​ 或其对应的类型声明。（2307）”

TypeScript will error with the following message: “Cannot find module …​ or its corresponding type declarations. (2307)”

当文件位于磁盘上而不是通过 HTTP 位于服务器上时，TypeScript 的模块解析会起作用。为了获取我们需要的信息，我们必须为 TypeScript 提供自己的解析。

TypeScript’s module resolution works when files are on your disk, not on a server via HTTP. To get the info we need, we have to provide TypeScript with a resolution of our own.

尽管我们从 URL 加载依赖项，但这些依赖项的类型信息仍存在于 NPM 中。对于lodash，您可以从 Definitely Typed 安装类型信息：

Even though we are loading dependencies from URLs, the type information for these dependencies lives with NPM. For lodash, you can install type information from Definitely Typed:

$  npm  install  -D  @types/lodash

$ npm install -D @types/lodash

对于自带类型的依赖项，你可以直接安装依赖项：

For dependencies that come with their own types, you can install the dependencies directly:

$  npm  install  -D  preact

$ npm install -D preact

安装类型后，使用path编译器选项中的属性来告诉 TypeScript 如何解析你的 URL：

Once the types are installed, use the path property in your compiler options to tell TypeScript how to resolve your URL:

// tsconfig.json
{
  "compilerOptions": {
    // ...
    "paths": {
      "https://esm.sh/lodash@4.17.21": [
        "node_modules/@types/lodash/index.d.ts"
      ]
    }
  }
}

// tsconfig.json
{
  "compilerOptions": {
    // ...
    "paths": {
      "https://esm.sh/lodash@4.17.21": [
        "node_modules/@types/lodash/index.d.ts"
      ]
    }
  }
}

请务必指向正确的文件！

Be sure to point to the right file!

如果您不想使用类型，或者只是找不到类型，那么还有一个逃生舱。在 TypeScript 中，我们可以使用any来有意禁用类型检查。对于模块，我们可以做一些非常类似的事情——忽略 TypeScript 错误：

There’s also an escape hatch if you don’t want to use typings, or if you just can’t find typings. Within TypeScript, we can use any to intentionally disable type-checking. For modules, we can do something very similar—ignore the TypeScript error:

// @ts-ignore
import _ from "https://esm.sh/lodash@4.17.21"

// @ts-ignore
import _ from "https://esm.sh/lodash@4.17.21"

ts-ignore删除类型检查中的下一行，并且可以在您想要忽略类型错误的地方使用（参见配方 1.4）。这实际上意味着您将无法获得依赖项的任何类型信息，并且可能会遇到错误，但对于您只需要但找不到任何类型的未维护的旧依赖项，这可能是最终的解决方案。

ts-ignore removes the next line from type-checking and can be used everywhere you want to ignore type errors (see Recipe 1.4). This effectively means that you won’t get any type information for your dependencies and you might run into errors, but it might be the ultimate solution for unmaintained, old dependencies that you just need but won’t find any types for.

问题

Problem

您想在 Node.js 中使用 ECMAScript 模块，并使用 CommonJS 库互操作性功能。

You want to use ECMAScript modules in Node.js and the CommonJS interoperability feature for libraries.

解决方案

Solution

将 TypeScript 的模块分辨率设置为"nodeNext"并将文件命名为.mts或.cts。

Set TypeScript’s module resolution to "nodeNext" and name your files .mts or .cts.

讨论

Discussion

随着 Node.js 的出现，CommonJS 模块系统已经成为 JavaScript 生态系统中最流行的模块系统之一。

With the advent of Node.js, the CommonJS module system has become one of the most popular module systems in the JavaScript ecosystem.

这个想法简单而有效：在一个模块中定义导出，并 在另一个模块中需要它们：

The idea is simple and effective: define exports in one module and require them in another:

// person.js
function printPerson(person) {
  console.log(person.name);
}

exports = {
  printPerson,
};

// index.js
const person = require("./person");
person.printPerson({ name: "Stefan", age: 40 });

// person.js
function printPerson(person) {
  console.log(person.name);
}

exports = {
  printPerson,
};

// index.js
const person = require("./person");
person.printPerson({ name: "Stefan", age: 40 });

该系统对 ECMAScript 模块产生了巨大影响，并且已成为 TypeScript 模块解析和转译器的默认系统。如果您查看示例 1-1中的 ECMAScript 模块语法，您会发现关键字允许不同的转译。这意味着，使用commonjs模块设置，您的importandexport语句将被转译为requireand exports。

This system has been a huge influence on ECMAScript modules and also has been the default for TypeScript’s module resolution and transpiler. If you look at the ECMAScript modules syntax in Example 1-1, you can see that the keywords allow for different transpilations. This means that with the commonjs module setting, your import and export statements are transpiled to require and exports.

// person.ts
type Person = {
  name: string;
  age: number;
};

export function printPerson(person) {
  console.log(person.name);
}

// index.ts
import * as person from "./person";
person.printPerson({ name: "Stefan", age: 40 });

// person.ts
type Person = {
  name: string;
  age: number;
};

export function printPerson(person) {
  console.log(person.name);
}

// index.ts
import * as person from "./person";
person.printPerson({ name: "Stefan", age: 40 });

随着 ECMAScript 模块的稳定，Node.js 也开始采用它们。尽管两个模块系统的基础看起来非常相似，但在细节上还是存在一些差异，例如处理默认导出或异步加载 ECMAScript 模块。

With ECMAScript modules stabilizing, Node.js has also started to adopt them. Even though the basics of both module systems seem to be very similar, there are some differences in the details, such as handling default exports or loading ECMAScript modules asynchronously.

由于无法将两个模块系统视为相同但语法不同的系统，Node.js 维护者决定为这两个系统留出空间，并分配不同的文件后缀以指示首选的模块类型。表 1-1显示了不同的后缀、它们在 TypeScript 中的命名方式、TypeScript 将它们编译成什么以及它们可以导入什么。由于 CommonJS 互操作性，可以从 ECMAScript 模块导入 CommonJS 模块，但反过来不行。

As there is no way to treat both module systems the same but with different syntax, the Node.js maintainers decided to give both systems room and assigned different file endings to indicate the preferred module type. Table 1-1 shows the different endings, how they’re named in TypeScript, what TypeScript compiles them to, and what they can import. Thanks to the CommonJS interoperability, it’s fine to import CommonJS modules from ECMAScript modules, but not the other way around.

在 NPM 上发布库的开发人员会在他们的package.json文件中获取额外信息，以指示包的主要类型（module或commonjs），并指向主文件或后备文件列表，以便模块加载器可以选择正确的文件：

Library developers who publish on NPM get extra information in their package.json file to indicate the main type of a package (module or commonjs), and to point to a list of main files or fallbacks so module loaders can pick up the right file:

// package.json
{
  "name": "dependency",
  "type": "module",
  "exports": {
     ".": {
        // Entry-point for `import "dependency"` in ES Modules
        "import": "./esm/index.js",
        // Entry-point for `require("dependency") in CommonJS
        "require": "./commonjs/index.cjs",
     },
  },
  // CommonJS Fallback
  "main": "./commonjs/index.cjs"
}

// package.json
{
  "name": "dependency",
  "type": "module",
  "exports": {
     ".": {
        // Entry-point for `import "dependency"` in ES Modules
        "import": "./esm/index.js",
        // Entry-point for `require("dependency") in CommonJS
        "require": "./commonjs/index.cjs",
     },
  },
  // CommonJS Fallback
  "main": "./commonjs/index.cjs"
}

在 TypeScript 中，你主要编写 ECMAScript 模块语法，并让编译器决定最终要创建哪种模块格式。现在可能有两种：CommonJS 和 ECMAScript 模块。

In TypeScript, you write mainly ECMAScript module syntax and let the compiler decide which module format to create in the end. Now there are possibly two: CommonJS and ECMAScript modules.

为了同时允许两者，您可以在tsconfig.json中将模块分辨率设置为NodeNext：

To allow for both, you can set module resolution in your tsconfig.json to NodeNext:

{
  "compilerOptions": {
    "module": "NodeNext"
    // ...
  }
}

{
  "compilerOptions": {
    "module": "NodeNext"
    // ...
  }
}

使用该标志，TypeScript 将根据依赖项 package.json中的描述选择正确的模块，识别.mts和.cts结尾，并按照表 1-1进行模块导入。

With that flag, TypeScript will pick up the right modules as described in your dependencies package.json, will recognize .mts and .cts endings, and will follow Table 1-1 for module imports.

对于开发人员来说，导入文件时会有所不同。由于 CommonJS 在导入时不需要结尾，因此 TypeScript 仍然支持没有结尾的导入。如果您只使用 CommonJS，则示例 1-1中的示例仍然有效。

For you as a developer, there are differences in importing files. Since CommonJS didn’t require endings when importing, TypeScript still supports imports without endings. The example in Example 1-1 still works, if all you use is CommonJS.

像在方案 1.8中一样，使用文件扩展名导入可以将模块导入 ECMAScript 模块和 CommonJS 模块中：

Importing with file endings, just like in Recipe 1.8, allows modules to be imported in both ECMAScript modules and CommonJS modules:

// index.mts
import * as person from "./person.js"; // works in both
person.printPerson({ name: "Stefan", age: 40});

// index.mts
import * as person from "./person.js"; // works in both
person.printPerson({ name: "Stefan", age: 40});

如果 CommonJS 互操作性不起作用，您可以随时使用语句require。将"node"全局类型添加到您的编译器选项中：

Should CommonJS interoperability not work, you can always fall back on a require statement. Add "node" as global types to your compiler options:

// tsconfig.json
{
  "compilerOptions": {
    "module": "NodeNext",
    "types": ["node"],
  }
}

// tsconfig.json
{
  "compilerOptions": {
    "module": "NodeNext",
    "types": ["node"],
  }
}

然后，使用此 TypeScript 特定的语法导入：

Then, import with this TypeScript-specific syntax:

// index.mts
import person = require("./person.cjs");

person.printPerson({ name: "Stefan", age: 40 });

// index.mts
import person = require("./person.cjs");

person.printPerson({ name: "Stefan", age: 40 });

在 CommonJS 模块中，这只是另一个require调用；在 ECMAScript 模块中，这将包括 Node.js 辅助函数：

In a CommonJS module, this will be just another require call; in ECMAScript modules, this will include Node.js helper functions:

// compiled index.mts
import { createRequire as _createRequire } from "module";
const __require = _createRequire(import.meta.url);
const person = __require("./person.cjs");
person.printPerson({ name: "Stefan", age: 40 });

// compiled index.mts
import { createRequire as _createRequire } from "module";
const __require = _createRequire(import.meta.url);
const person = __require("./person.cjs");
person.printPerson({ name: "Stefan", age: 40 });

请注意，这会降低与浏览器等非 Node.js 环境的兼容性，但最终可能会解决互操作性问题。

Note that this will reduce compatibility with non-Node.js environments like the browser, but it might eventually fix interoperability issues.

问题

Problem

您想将 TypeScript 与 Deno（一种用于浏览器外应用程序的现代 JavaScript 运行时）一起使用。

You want to use TypeScript with Deno, a modern JavaScript runtime for applications outside the browser.

解决方案

Solution

这很简单；TypeScript 是内置的。

That’s easy; TypeScript is built in.

讨论

Discussion

Deno 是一个现代 JavaScript 运行时，由开发 Node.js 的同一批人创建。Deno 在许多方面与 Node.js 相似，但也有显著差异：

Deno is a modern JavaScript runtime created by the same people who developed Node.js. Deno is similar to Node.js in many ways, but with significant differences:

• Deno 采用 Web 平台标准作为其主要 API，这意味着您将更容易将代码从浏览器移植到服务器。

• Deno adopts web platform standards for their main APIs, meaning that you will find it easier to port code from the browser to the server.

• 仅当您明确激活它时，它才允许文件系统或网络访问。

• It allows file system or network access only if you explicitly activate it.

• 它不通过集中式注册表处理依赖关系，而是再次采用浏览器功能通过 URL 来处理。

• It doesn’t handle dependencies via a centralized registry, but—again adopting browser features—via URLs.

哦，它还带有内置开发工具和 TypeScript！

Oh, and it comes with built-in development tooling and TypeScript!

如果你想尝试 TypeScript，Deno 是门槛最低的工具。无需下载任何其他工具（tsc编译器已内置），无需 TypeScript 配置。你只需编写.ts文件，Deno 会处理其余的事情：

Deno is the tool with the lowest barrier if you want to try TypeScript. No need to download any other tool (the tsc compiler is already built in), no need for TypeScript configurations. You write .ts files, and Deno handles the rest:

// main.ts
function sayHello(name: string) {
  console.log(`Hello ${name}`);
}

sayHello("Stefan");

// main.ts
function sayHello(name: string) {
  console.log(`Hello ${name}`);
}

sayHello("Stefan");

$  deno 运行 main.ts

$ deno run main.ts

Deno 的 TypeScript 可以做所有tsc能做的事情，并且会随着 Deno 的每次更新而更新。但是，当你想配置它时，会有一些不同。

Deno’s TypeScript can do everything tsc can do, and it is updated with every Deno update. However, there are some differences when you want to configure it.

首先，默认配置与 发布的默认配置在默认设置上有差异tsc --init。严格模式功能标志的设置不同，并且它包含对 React 的支持（在服务器端！）。

First, the default configuration has differences in its default settings as opposed to the default configuration issued by tsc --init. Strict mode feature flags are set differently, and it includes support for React (on the server side!).

要更改配置，你应该在根文件夹中创建一个deno.json文件。除非你告诉它不要这样做，否则 Deno 会自动选择它。deno.json包含Deno 运行时的几个配置，包括 TypeScript 编译器选项：

To make changes to the configuration, you should create a deno.json file in your root folder. Deno will automatically pick this up, unless you tell it not to. deno.json includes several configurations for the Deno runtime, including TypeScript compiler options:

{
  "compilerOptions": {
    // Your TSC compiler options
  },
  "fmt": {
    // Options for the auto-formatter
  },
  "lint": {
    // Options for the linter
  }
}

{
  "compilerOptions": {
    // Your TSC compiler options
  },
  "fmt": {
    // Options for the auto-formatter
  },
  "lint": {
    // Options for the linter
  }
}

您可以在Deno 网站上看到更多可能性。

You can see more possibilities on the Deno website.

默认库也不同。尽管 Deno 支持 Web 平台标准并具有与浏览器兼容的 API，但它需要进行一些删减，因为没有图形用户界面。这就是为什么某些类型（例如 DOM 库）与 Deno 提供的内容发生冲突的原因。

The default libraries are different as well. Even though Deno supports web platform standards and has browser-compatible APIs, it needs to make some cuts because there is no graphical user interface. That’s why some types—for example, the DOM library—clash with what Deno provides.

一些感兴趣的库是：

Some libraries of interest are:

• deno.ns，默认的 Deno 命名空间

• deno.ns, the default Deno namespace

• deno.window，Deno 的全局对象

• deno.window, the global object for Deno

• deno.worker，Deno 运行时中的 Web Workers 等效项

• deno.worker, the equivalent for Web Workers in the Deno runtime

DOM 和子集包含在 Deno 中，但默认情况下未启用。如果你的应用程序同时针对浏览器和 Deno，请将 Deno 配置为包含所有浏览器和 Deno 库：

DOM and subsets are included in Deno, but they are not switched on by default. If your application targets both the browser and Deno, configure Deno to include all browser and Deno libraries:

// deno.json
{
  "compilerOptions": {
    "target": "esnext",
    "lib": ["dom", "dom.iterable", "dom.asynciterable", "deno.ns"]
  }
}

// deno.json
{
  "compilerOptions": {
    "target": "esnext",
    "lib": ["dom", "dom.iterable", "dom.asynciterable", "deno.ns"]
  }
}

Aleph.js是一个针对 Deno 和浏览器的框架的示例。

Aleph.js is an example of a framework that targets both Deno and the browser.

Deno 的另一个不同之处在于依赖项的类型信息是如何分布的。Deno 中的外部依赖项通过 CDN 中的 URL 加载。Deno 本身将其标准库托管在https://deno.land/std上。

Also different with Deno is how type information for dependencies is distributed. External dependencies in Deno are loaded via URLs from a CDN. Deno itself hosts its standard library at https://deno.land/std.

但你也可以使用esm.sh或unpkg之类的 CDN ，如配方 1.8中所示。这些 CDN 通过X-TypeScript-Types在 HTTP 请求中发送标头来分发类型，显示 Deno 将加载类型声明。这也适用于没有第一方类型声明但依赖于 Definitely Typed 的依赖项。

But you can also use CDNs like esm.sh or unpkg, like in Recipe 1.8. These CDNs distribute types by sending an X-TypeScript-Types header with the HTTP request, showing Deno was to load type declarations. This also goes for dependencies that don’t have first-party type declarations but rely on Definitely Typed.

因此，当您安装依赖项时，Deno 不仅会获取源文件，还会获取所有类型信息。

So the moment you install your dependency, Deno will fetch not only the source files but also all the type information.

如果您不从 CDN 加载依赖项而是在本地加载，则可以在导入依赖项时指向类型声明文件：

If you don’t load a dependency from a CDN but rather have it locally, you can point to a type declaration file the moment you import the dependency:

// @deno-types="./charting.d.ts"
import * as charting from "./charting.js";

// @deno-types="./charting.d.ts"
import * as charting from "./charting.js";

或者包含对库本身类型的引用：

or include a reference to the typings in the library itself:

// charting.js
/// <reference types="./charting.d.ts" />

// charting.js
/// <reference types="./charting.d.ts" />

此引用也称为三斜杠指令，是 TypeScript 功能，而不是 Deno 功能。有各种三斜杠指令，主要用于 ECMAScript 之前的模块依赖系统。文档提供了非常好的概述。但是，如果您坚持使用 ECMAScript 模块，则很可能不会使用三斜杠指令。

This reference is also called a triple-slash directive and is a TypeScript feature, not a Deno feature. There are various triple-slash directives, mostly used for pre-ECMAScript module dependency systems. The documentation gives a really good overview. If you stick with ECMAScript modules, you most likely won’t use triple-slash directives, though.

问题

Problem

您想在某个框架或平台上使用 TypeScript，但不知道从哪里开始配置。

You want to use TypeScript for a certain framework or platform but don’t know where to start with your configuration.

解决方案

Solution

使用tsconfig/bases中的预定义配置并从那里扩展。

Use a predefined configuration from tsconfig/bases and extend from there.

讨论

Discussion

就像 Def​​initely Typed 托管社区维护的热门库类型定义一样，tsconfig/bases托管一组社区维护的 TypeScript 配置建议，您可以将其用作自己项目的起点。这包括 Ember.js、Svelte 或 Next.js 等框架以及 Node.js 和 Deno 等 JavaScript 运行时。

Just like Definitely Typed hosts community-maintained type definitions for popular libraries, tsconfig/bases hosts a set of community-maintained recommendations for TypeScript configurations you can use as a starting point for your own project. This includes frameworks like Ember.js, Svelte, or Next.js as well as JavaScript runtimes like Node.js and Deno.

配置文件被减少到最低限度，主要处理推荐的库、模块和目标设置，以及一堆适合相应环境的严格模式标志。

The configuration files are reduced to a minimum, dealing mostly with recommended libraries, modules, and target settings, and a bunch of strict mode flags that make sense for the respective environment.

例如，这是针对 Node.js 18 的推荐配置，具有推荐的严格模式设置和 ECMAScript 模块：

For example, this is the recommended configuration for Node.js 18, with a recommended strict mode setting and with ECMAScript modules:

{
  "$schema": "https://json.schemastore.org/tsconfig",
  "display": "Node 18 + ESM + Strictest",
  "compilerOptions": {
    "lib": [
      "es2022"
    ],
    "module": "es2022",
    "target": "es2022",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "moduleResolution": "node",
    "allowUnusedLabels": false,
    "allowUnreachableCode": false,
    "exactOptionalPropertyTypes": true,
    "noFallthroughCasesInSwitch": true,
    "noImplicitOverride": true,
    "noImplicitReturns": true,
    "noPropertyAccessFromIndexSignature": true,
    "noUncheckedIndexedAccess": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "importsNotUsedAsValues": "error",
    "checkJs": true
  }
}

{
  "$schema": "https://json.schemastore.org/tsconfig",
  "display": "Node 18 + ESM + Strictest",
  "compilerOptions": {
    "lib": [
      "es2022"
    ],
    "module": "es2022",
    "target": "es2022",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "moduleResolution": "node",
    "allowUnusedLabels": false,
    "allowUnreachableCode": false,
    "exactOptionalPropertyTypes": true,
    "noFallthroughCasesInSwitch": true,
    "noImplicitOverride": true,
    "noImplicitReturns": true,
    "noPropertyAccessFromIndexSignature": true,
    "noUncheckedIndexedAccess": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "importsNotUsedAsValues": "error",
    "checkJs": true
  }
}

要使用此配置，请通过 NPM 安装它：

To use this configuration, install it via NPM:

$  npm  install  --save-dev  @tsconfig/node18-strictest-esm

$ npm install --save-dev @tsconfig/node18-strictest-esm

并将其连接到你自己的 TypeScript 配置中：

and wire it up in your own TypeScript configuration:

{
  "extends": "@tsconfig/node18-strictest-esm/tsconfig.json",
  "compilerOptions": {
    // ...
  }
}

{
  "extends": "@tsconfig/node18-strictest-esm/tsconfig.json",
  "compilerOptions": {
    // ...
  }
}

这将从预定义配置中获取所有设置。您现在可以开始设置自己的属性，例如根目录和输出目录。

This will pick up all the settings from the predefined configuration. You can now start setting your own properties, for example, root and out directories.